Developer CD Series 1995 June: Reference Library/Dev.CD Jun 95/Dev.CD Jun 95.toast/What's New?/New System Software Extensions/QuickDraw 3D ß/Programming/Interfaces/QD3DIO.h

C/C++ Source or Header | 1995-04-12 | 20.5 KB | 729 lines | [TEXT/MPS ]

/******************************************************************************
 **                                                                             **
 **     Module:        QD3DIO.h                                                 **
 **                                                                          **
 **                                                                             **
 **     Purpose:    QuickDraw 3D IO API                                         **
 **                                                                          **
 **                                                                             **
 **     Copyright (C) 1992-1995 Apple Computer, Inc.  All rights reserved.   **
 **                                                                             **
 **                                                                          **
 *****************************************************************************/
#ifndef QD3DIO_h
#define QD3DIO_h

#if PRAGMA_ONCE
    #pragma once
#endif

#include "QD3DDrawContext.h"
#include "QD3DView.h"

#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */

/******************************************************************************
 **                                                                          **
 **                                Basic Types                                     **
 **                                                                          **
 *****************************************************************************/

typedef unsigned char    TQ3Uns8;    /* 1 byte unsigned integer                 */
typedef signed   char    TQ3Int8;    /* 1 byte signed integer                 */
typedef unsigned short    TQ3Uns16;    /* 2 byte unsigned integer                 */
typedef signed   short    TQ3Int16;    /* 2 byte signed integer                 */
typedef unsigned long    TQ3Uns32;    /* 4 byte unsigned integer                 */
typedef signed   long    TQ3Int32;    /* 4 byte signed integer                 */

typedef struct TQ3Uns64 {
    unsigned long    hi;
    unsigned long     lo;
} TQ3Uns64;                            /* 8 byte unsigned integer                 */

typedef struct TQ3Int64 {
    signed long        hi;
    unsigned long    lo;
} TQ3Int64;                            /* 8 byte signed integer                 */

typedef float            TQ3Float32;    /* 4 byte floating point number             */
typedef double            TQ3Float64;    /* 8 byte floating point number             */

typedef TQ3Uns32        TQ3Size;

/******************************************************************************
 **                                                                          **
 **                                File Types                                     **
 **                                                                          **
 *****************************************************************************/

typedef enum TQ3FileModeMasks {
    kQ3FileModeNormal        = 0,
    kQ3FileModeStream        = 1 << 0,
    kQ3FileModeDatabase        = 1 << 1,
    kQ3FileModeText            = 1 << 2
} TQ3FileModeMasks;

typedef unsigned long TQ3FileMode;

typedef enum TQ3FileStatus {
    kQ3FileStatusDone,
    kQ3FileStatusRetraverse,
    kQ3FileStatusError,
    kQ3FileStatusCancelled
} TQ3FileStatus;

/******************************************************************************
 **                                                                          **
 **                                Method Types                                 **
 **                                                                          **
 *****************************************************************************/

/*
 * IO Methods
 *
 *    The IO system treats all objects as groups of typed information.
 *
 *    All objects in the metafile are made up of a "root" or parent object which
 *    defines the instantiated object type.
 *
 *    Objects are often appended with additional child objects which append
 *    an object by appending more information, or filling out default fields.
 *
 *    Parents and children are encapsulated in a container object, which delimits
 *    the entire object.
 *
 *    Single parents have no container. Children objects may be parents and have
 *    children.
 *
 *    e.g.
 *
 *    OrderedList ()                # Single parent, no container, no children
 *    Point (0 0 1)                # Single parent, no container, no children
 *    Container (                    # Contained parent object, has children
 *        GeometryAttributeSet ()    # Parent or "root" object (1)
 *        DiffuseColor (1 0 0)    # Child object
 *        SpecularControl (0.5)    # Child object
 *    )
 *    Container (
 *        Point (0 0 1)            # Parent object, contained, has children
 *        Container (                # Contained child object, has children
 *            GeometryAttributeSet ()    # Child of "Point", also Parent object (2)
 *            DiffuseColor (0 1 0)    # Child object
 *        )
 *    )
 *    EndGroup ()
 *
 *    Many object types may either be parent objects, or may be a child object of
 *    another parent, or may be both.
 *    In the example above,
 *        the DiffuseColor is solely a child object
 *        the Point is solely a parent object
 *        the GeometryAttributeSet is both a parent object (1), then a child
 *        object (2).
 *
 *    For example,
 *    - a "GeometryAttributeSet" is a parent object and may also be the child
 *        object of certain geometries.
 *    - a "DiffuseColor" is only a child object.
 *    - a "View" is only a parent object.
 *
 *    Writing is straightforward: an object writes itself and any other objects
 *    that make it up.
 *
 *    The TQ3ObjectTraverseMethod method first calculates an object's required
 *    size on disk, and writes the parent object data.
 *
 *    The traverse method may then call other traverse methods to write out
 *    multiple objects bundled together in a container.
 *
 *    The TQ3ObjectWriteMethod method physically writes the root object data of
 *    this object to the file.
 *
 *    Reading is somewhat more complicated: either a parent object must know
 *    how to attach a child object to itself, or the child must know how to
 *    attach itself to its parent. Some FILE objects are not actaully "objects"
 *    in memory, such as "elements" of a set.
 *
 *    These object register an TQ3ObjectReadData method, in which it is passed
 *    either a pointer to a buffer to read into, or an object to attach its data
 *    to.
 *
 *    Some children are ALWAYS children, meaning they always have a parent.
 *    Some children may have children of their own.
 *
 *    The TQ3ObjectReadMethod method reads the root object data of an object from
 *    the file, creates an instance of this object, placing it in the object
 *    return value.
 *
 *    The TQ3ObjectReadMethod method may register a means of attaching a child
 *    object to it.
 *
 *    If the child object is encountered, the file system uses the registered
 *    information to read the child object. The parent, in this case, is attaching
 *    the child to itself. The child's TQ3ReadObjectMethod is called if it is
 *    encountered.
 *
 *    Otherwise, if the parent read method doesn't register a means of attaching
 *    the child, and the subobject is an instantiable object, the object is read,
 *    and the child's "attach" method is called to attach the child to the parent.
 *
 *    If the subobject is not instantiable, and the parent did not register a
 *    means of attachment, the child object's readData call is called, the the
 *    parent, and a NULL data pointer.
 *
 *    The TQ3ObjectAttachMethod simply determines if the child object (which was
 *    either "just read" or was referenced elsewhere) should attach the child
 *    to the parent, and does so. If this method cannot attach the two objects,
 *    it should return kQ3Failure.
 *
 *    So, in the incestuous world of objects, the parents may choose whatever
 *    objects they wish as children (assuming they know how the child is
 *    read, of course), or, the children may decide who they would like to have
 *    as parents (assuming they know how to attach themselves to the parent,
 *    of course).
 *
 *    The important lesson is: The parent always wins. The parent attachment
 *    always overrides a child's attachment.
 *
 */
typedef TQ3Status (*TQ3ObjectTraverseMethod)(
    TQ3Object            object,
    TQ3FileObject        file);

typedef TQ3Status (*TQ3ObjectWriteMethod)(
    const void            *object,
    TQ3FileObject        file);

typedef TQ3Status (*TQ3ObjectReadMethod)(
    TQ3Object            *object,
    TQ3FileObject        file);

/* TQ3ObjectReadDataMethod

   For "elements" (meaning "attributes", too), you must allocate stack space and call
    Q3Set_Add on "parentObject", which is an TQ3SetObject.

    Otherwise, parentObject is an object to attach your custom data to.
*/

typedef TQ3Status (*TQ3ObjectReadDataMethod)(
    TQ3Object            parentObject,
    TQ3FileObject        file);

typedef TQ3Status (*TQ3ObjectAttachMethod)(
    TQ3Object            childObject,
    TQ3Object            parentObject);

typedef unsigned long    TQ3FileVersion;

#define kQ3OldVersion                    Q3FileVersion(0,2)
#define kQ3CurrentVersion                Q3FileVersion(0,5)

/******************************************************************************
 **                                                                             **
 **                                Version Macros                                 **
 **                                                                             **
 *****************************************************************************/

#define Q3FileVersion(majorVersion, minorVersion)    (TQ3FileVersion) \
    ((((TQ3Uns32) majorVersion & 0xFFFF) << 16) | ((TQ3Uns32) minorVersion & 0xFFFF))

/******************************************************************************
 **                                                                             **
 **                            String Constants                                 **
 **                                                                             **
 *****************************************************************************/

#define kQ3StringMaximumLength            1024

/******************************************************************************
 **                                                                             **
 **                            File Routines                                     **
 **                                                                             **
 *****************************************************************************/

/*
 * Creation and accessors
 */
EXPORT TQ3FileObject Q3File_New(
    void);

EXPORT TQ3Status Q3File_GetStorage(
    TQ3FileObject        file,
    TQ3StorageObject    *storage);

EXPORT TQ3Status Q3File_SetStorage(
    TQ3FileObject        file,
    TQ3StorageObject    storage);

/*
 * Opening, and accessing "open" state, closing/cancelling
 */
EXPORT TQ3Status Q3File_OpenRead(
    TQ3FileObject        file,
    TQ3FileMode            *mode);

EXPORT TQ3Status Q3File_OpenWrite(
    TQ3FileObject        file,
    TQ3FileMode            mode);

EXPORT TQ3Status Q3File_IsOpen(
    TQ3FileObject        file,
    TQ3Boolean            *isOpen);

EXPORT TQ3Status Q3File_GetMode(
    TQ3FileObject        file,
    TQ3FileMode            *mode);

EXPORT TQ3Status Q3File_GetVersion(
    TQ3FileObject        file,
    TQ3FileVersion        *version);

EXPORT TQ3Status Q3File_Close(
    TQ3FileObject        file);

EXPORT TQ3Status Q3File_Cancel(
    TQ3FileObject        file);

/*
 * Writing (Application)
 */
EXPORT TQ3Status Q3View_StartWriting(
    TQ3ViewObject         view,
    TQ3FileObject        file);

EXPORT TQ3ViewStatus Q3View_EndWriting(
    TQ3ViewObject         view);

/*
 * Reading (Application)
 */
EXPORT TQ3Status Q3File_GetNextObjectType(
    TQ3FileObject        file,
    TQ3ObjectType        *type);

EXPORT TQ3Status Q3File_ReadObject(
    TQ3FileObject        file,
    TQ3Object            *object);

EXPORT TQ3Status Q3File_SkipObject(
    TQ3FileObject        file);

EXPORT TQ3Status Q3File_IsEndOfFile(
    TQ3FileObject        file,
    TQ3Boolean            *isEOF);

/*
 * Idling
 */
typedef void (*TQ3FileIdleMethod)(
    TQ3FileObject        file,
    const void            *idlerData);

EXPORT TQ3Status Q3File_SetIdleMethod(
    TQ3FileObject        file,
    TQ3FileIdleMethod    idle,
    const void            *idleData);

/*
 * Custom object writing (for use in appending subobjects)
 */
EXPORT TQ3Status Q3FileWriteState_SetObjectWriteData(
    TQ3FileObject        file,
    const void            *data,
    TQ3Size                size);

EXPORT TQ3Status Q3FileWriteState_TraverseSubObject(
    TQ3FileObject        file,
    TQ3Object            subObject);

/*
 * Custom object reading (for use in reading/parsing subobjects)
 */
EXPORT TQ3Status Q3FileReadState_SubObjectsRemain(
    TQ3FileObject        file,
    TQ3Boolean            *subObjectsRemain);

TQ3Status Q3FileReadState_AddSubObjectFilter(
    TQ3FileObject        file,
    TQ3ObjectType        subObjectIsType);

EXPORT TQ3Status Q3FileReadState_ReadSubObject(
    TQ3FileObject        file,
    TQ3ObjectType        *subObjectIsType,
    TQ3Object            *object);

/******************************************************************************
 **                                                                             **
 **                            Primitives routines                                 **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3Uns8_Read(
    TQ3Uns8                *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns8_Write(
    const TQ3Uns8        data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns16_Read(
    TQ3Uns16                *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns16_Write(
    const TQ3Uns16        data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns32_Read(
    TQ3Uns32                *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns32_Write(
    const TQ3Uns32        data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Int32_Read(
    TQ3Int32            *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Int32_Write(
    const TQ3Int32        data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns64_Read(
    TQ3Uns64            *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Uns64_Write(
    const TQ3Uns64        data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Float32_Read(
    TQ3Float32            *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Float32_Write(
    const TQ3Float32    data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Float64_Read(
    TQ3Float64            *data,
    TQ3FileObject        file);

EXPORT TQ3Status Q3Float64_Write(
    const TQ3Float64    data,
    TQ3FileObject        file);

EXPORT TQ3Size Q3Size_Pad(
    TQ3Size                size);

/*
 * Pass a pointer to a buffer of kQ3StringMaximumLength bytes
 */
EXPORT TQ3Status Q3String_Read(
    char                *data,
    unsigned long        *length,
    TQ3FileObject        file);

EXPORT TQ3Status Q3String_Write(
    const char            *data,
    TQ3FileObject        file);

/*
 * This call will read Q3Size_Pad(size) bytes,
 *    but only place size bytes into data.
 */
EXPORT TQ3Status Q3RawData_Read(
    unsigned char        *data,
    unsigned long        size,
    TQ3FileObject        file);

/*
 * This call will write Q3Size_Pad(size) bytes,
 *    adding 0's to pad to the nearest 4 byte boundary.
 */
EXPORT TQ3Status Q3RawData_Write(
    const unsigned char    *data,
    unsigned long        size,
    TQ3FileObject        file);

/******************************************************************************
 **                                                                             **
 **                        Convenient Primitives routines                         **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3Point2D_Read(
    TQ3Point2D                    *point2D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Point2D_Write(
    const TQ3Point2D            *point2D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Point3D_Read(
    TQ3Point3D                    *point3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Point3D_Write(
    const TQ3Point3D            *point3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3RationalPoint3D_Read(
    TQ3RationalPoint3D            *point3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3RationalPoint3D_Write(
    const TQ3RationalPoint3D    *point3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3RationalPoint4D_Read(
    TQ3RationalPoint4D            *point4D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3RationalPoint4D_Write(
    const TQ3RationalPoint4D    *point4D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Vector2D_Read(
    TQ3Vector2D                    *vector2D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Vector2D_Write(
    const TQ3Vector2D            *vector2D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Vector3D_Read(
    TQ3Vector3D                    *vector3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Vector3D_Write(
    const TQ3Vector3D            *vector3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Matrix4x4_Read(
    TQ3Matrix4x4                *matrix4x4,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Matrix4x4_Write(
    const TQ3Matrix4x4            *matrix4x4,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Tangent2D_Read(
    TQ3Tangent2D                *tangent2D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Tangent2D_Write(
    const TQ3Tangent2D            *tangent2D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Tangent3D_Read(
    TQ3Tangent3D                *tangent3D,
    TQ3FileObject                file);

EXPORT TQ3Status Q3Tangent3D_Write(
    const TQ3Tangent3D            *tangent3D,
    TQ3FileObject                file);

/*    This call affects only text Files - it is a no-op in binary files */

EXPORT TQ3Status Q3Comment_Write(
    char                        *comment,
    TQ3FileObject                file);

/******************************************************************************
 **                                                                             **
 **                            Unknown Object                                      **
 **                                                                             **
 **        Unknown objects are generated when reading files which contain         **
 **        custom data which has not been registered in the current             **
 **        instantiation of QuickDraw 3D.                                         **
 **                                                                             **
 *****************************************************************************/

/******************************************************************************
 **                                                                             **
 **                            Unknown Routines                                 **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3ObjectType Q3Unknown_GetType(
    TQ3UnknownObject        unknownObject);

EXPORT TQ3Status Q3Unknown_GetDirtyState(
    TQ3UnknownObject        unknownObject,
    TQ3Boolean                *isDirty);

EXPORT TQ3Status Q3Unknown_SetDirtyState(
    TQ3UnknownObject        unknownObject,
    TQ3Boolean                isDirty);


/******************************************************************************
 **                                                                             **
 **                        Unknown Text Routines                                 **
 **                                                                             **
 *****************************************************************************/

typedef struct TQ3UnknownTextData {
    char                    *objectName;    /* '\0' terminated */
    char                    *contents;        /* '\0' terminated */
} TQ3UnknownTextData;

EXPORT TQ3Status Q3UnknownText_GetData(
    TQ3UnknownObject        unknownObject,
    TQ3UnknownTextData        *unknownTextData);

EXPORT TQ3Status Q3UnknownText_EmptyData(
    TQ3UnknownTextData        *unknownTextData);


/******************************************************************************
 **                                                                             **
 **                        Unknown Binary Routines                                 **
 **                                                                             **
 *****************************************************************************/

typedef struct TQ3UnknownBinaryData {
    TQ3ObjectType            objectType;
    unsigned long            size;
    char                    *contents;
} TQ3UnknownBinaryData;

EXPORT TQ3Status Q3UnknownBinary_GetData(
    TQ3UnknownObject            unknownObject,
    TQ3UnknownBinaryData        *unknownBinaryData);

EXPORT TQ3Status Q3UnknownBinary_EmptyData(
    TQ3UnknownBinaryData        *unknownBinaryData);


/******************************************************************************
 **                                                                             **
 **                            ViewHints routines                                  **
 **                                                                             **
 **        ViewHints are an object in a metafile to give you some hints on how  **
 **        to render a scene.    You may create a view with any of the objects      **
 **        retrieved from it, or you can just throw it away.                     **
 **                                                                             **
 **        To write a view hints to a file, create a view hints object from a      **
 **        view and write the view hints.                                         **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3SharedObject Q3ViewHints_New(
    TQ3ViewObject            view);

EXPORT TQ3Status Q3ViewHints_SetRenderer(
    TQ3SharedObject            viewHints,
    TQ3RendererObject        renderer);

EXPORT TQ3Status Q3ViewHints_GetRenderer(
    TQ3SharedObject            viewHints,
    TQ3RendererObject        *renderer);

EXPORT TQ3Status Q3ViewHints_SetCamera(
    TQ3SharedObject            viewHints,
    TQ3CameraObject            camera);

EXPORT TQ3Status Q3ViewHints_GetCamera(
    TQ3SharedObject            viewHints,
    TQ3CameraObject            *camera);

EXPORT TQ3Status Q3ViewHints_SetLightGroup(
    TQ3SharedObject            viewHints,
    TQ3GroupObject            lightGroup);

EXPORT TQ3Status Q3ViewHints_GetLightGroup(
    TQ3SharedObject            viewHints,
    TQ3GroupObject            *lightGroup);

EXPORT TQ3Status Q3ViewHints_SetAttributeSet(
    TQ3SharedObject            viewHints,
    TQ3AttributeSet            attributeSet);

EXPORT TQ3Status Q3ViewHints_GetAttributeSet(
    TQ3SharedObject            viewHints,
    TQ3AttributeSet            *attributeSet);

EXPORT TQ3Status Q3ViewHints_SetDimensionsState(
    TQ3SharedObject            viewHints,
    TQ3Boolean                isValid);

EXPORT TQ3Status Q3ViewHints_GetDimensionsState(
    TQ3SharedObject            viewHints,
    TQ3Boolean                *isValid);

EXPORT TQ3Status Q3ViewHints_SetDimensions(
    TQ3SharedObject            viewHints,
    unsigned long            width,
    unsigned long            height);

EXPORT TQ3Status Q3ViewHints_GetDimensions(
    TQ3SharedObject            viewHints,
    unsigned long            *width,
    unsigned long            *height);

EXPORT TQ3Status Q3ViewHints_SetMaskState(
    TQ3SharedObject            viewHints,
    TQ3Boolean                isValid);

EXPORT TQ3Status Q3ViewHints_GetMaskState(
    TQ3SharedObject            viewHints,
    TQ3Boolean                *isValid);

EXPORT TQ3Status Q3ViewHints_SetMask(
    TQ3SharedObject            viewHints,
    const TQ3Bitmap            *mask);

EXPORT TQ3Status Q3ViewHints_GetMask(
    TQ3SharedObject            viewHints,
    TQ3Bitmap                *mask);

/* Call Q3Bitmap_Empty when done with the mask    */

EXPORT TQ3Status Q3ViewHints_SetClearImageMethod(
    TQ3SharedObject                    viewHints,
    TQ3DrawContextClearImageMethod    clearMethod);

EXPORT TQ3Status Q3ViewHints_GetClearImageMethod(
    TQ3SharedObject                    viewHints,
    TQ3DrawContextClearImageMethod    *clearMethod);

EXPORT TQ3Status Q3ViewHints_SetClearImageColor(
    TQ3SharedObject            viewHints,
    const TQ3ColorARGB         *color);

EXPORT TQ3Status Q3ViewHints_GetClearImageColor(
    TQ3SharedObject            viewHints,
    TQ3ColorARGB             *color);

#if defined(ESCHER_VER_15) && ESCHER_VER_15

EXPORT TQ3Status Q3ViewHints_SetBackgroundShader(
    TQ3SharedObject            viewHints,
    TQ3ShaderObject            backgroundShader);

EXPORT TQ3Status Q3ViewHints_GetBackgroundShader(
    TQ3SharedObject            viewHints,
    TQ3ShaderObject            *backgroundShader);

EXPORT TQ3Status Q3ViewHints_SetAtmosphericShader(
    TQ3SharedObject            viewHints,
    TQ3ShaderObject            atmospheric);

EXPORT TQ3Status Q3ViewHints_GetAtmosphericShader(
    TQ3SharedObject            viewHints,
    TQ3ShaderObject            *atmospheric);

#endif    /*  ESCHER_VER_15  */

#ifdef __cplusplus
}
#endif    /* __cplusplus */

#endif /* QD3DIO_h */